feat(ci): gate merges on maintainer approval via a required status check - #3176

Summary

Adds a OpenShell / Core Approval commit status that passes only when someone listed in MAINTAINERS.md has approved the pull request. Once registered on ruleset 13332227 it becomes the approval gate, which is what makes it safe to disable the CODEOWNERS wildcard in #3168.

The motivating problem is that every native GitHub mechanism enforcing who must approve also notifies them:

A required status check is the only primitive that gates a merge silently. That splits enforcement from notification: this PR is the enforcement half. Targeted notification (area labels, per-area rosters) follows separately.

A file-based approver list also solves the outside-collaborator problem — three of thirteen maintainers cannot join an NVIDIA org team, but can be listed in a file.

Related Issue

No issue required. This does not touch OpenShell platform code — it is maintenance of the project's own review machinery, and is non-breaking as merged. The gate only starts enforcing when the status context is added to ruleset 13332227, which is a separate manual step (see Rollout).

Changes

• tasks/scripts/core_approval.py — stdlib-only helper. decide parses MAINTAINERS.md, folds the review list to each reviewer's latest decisive position, and prints state<TAB>description. diff renders the approver-set delta between two versions of the file.
• tasks/scripts/core_approval_test.py — 17 tests. tasks/test.toml gains test:core-approval.
• .github/workflows/core-approval.yml — publishes the status on pull_request_target, pull_request_review, merge_group, and workflow_dispatch.
• .github/workflows/maintainers-change-alert.yml — comments the added/removed handles on PRs touching MAINTAINERS.md, so reviewers see the delta instead of diffing a markdown table.
• .github/zizmor.yml — two dangerous-triggers suppressions for the new workflows.

Security invariants

1. Never check out or execute PR head code. pull_request_target runs with a write-capable token; executing contributor code under it is the standard escalation. The checkout is pinned to ref: main with a sparse checkout of only the helper script and persist-credentials: false.
2. MAINTAINERS.md is read from main, never the PR ref. Otherwise a contributor adds themselves in their own PR and self-approves.
3. Fail closed. An unparseable or empty list fails. No error path can publish success.

No ${{ }} interpolation appears inside any run: block; every context value routes through env:.

Why this trigger set

pull_request does not re-fire when someone approves, so the check would go stale red forever. pull_request_review fires but its jobs are not auto-surfaced as PR checks, so the status is POSTed explicitly. Fork PRs get a read-only token under pull_request and cannot POST at all; pull_request_target and pull_request_review both run in base-repo context.

merge_group publishes success unconditionally. A merge group only forms after the PR already satisfied this gate, and approvals cannot change while an entry sits in the queue. Without this, a required check that never reports on the merge-group ref stalls every entry for the full check_response_timeout_minutes (60).

Testing

• mise run pre-commit passes
• Unit tests added — 17 tests covering the valid table, a reformatted table, a zero-handle table (fails closed), self-approval, non-maintainer approval, dismissal and change-request semantics, out-of-order review IDs, and description truncation at 140 characters
• E2E tests added/updated — not applicable

There is no pre-merge dry run, by construction. pull_request_target runs the base branch's workflow definition, so this workflow cannot be exercised from its own PR. if: github.repository_owner == 'NVIDIA' also keeps it from running on forks. Behavior is covered by unit tests here and verified live after merge, before the check is made required.

Reviewer notes

• No $GITHUB_ENV writes. An earlier revision passed the head SHA between steps via $GITHUB_ENV, which trips zizmor's github-env rule under pull_request_target and fails the code-scanning check. The workflow now uses step outputs (steps.publish.outputs.posted / head_sha), which carry the same values without granting later steps an attacker-shaped environment. Note that the Zizmor High report job is informational, but the SARIF it uploads feeds a separate Advanced Security zizmor check that does fail on new alerts.
• Residual gap: on workflow_dispatch, no SHA is knowable until the PR lookup runs, so a failure strictly before that point publishes nothing and logs a warning. A failure after the lookup is covered by the head_sha step output. Every other event resolves the SHA from the event payload.
• Stale-dismissal race: the ruleset sets dismiss_stale_reviews_on_push: true. A push and a dismissal can interleave, but the check re-runs on synchronize, so it converges.
• Admin bypass is unchanged. Admins can bypass this check exactly as they can bypass today's CODEOWNERS gate. Reducing the admin surface is deliberately out of scope.
• johnnygreco holds admin via openshell-codeowners but is absent from MAINTAINERS.md. Deferred; revisit when the team list is reconciled.

Rollout

Order matters — reversing steps 1–3 and 4 blocks every open PR.

1. Merge this PR.
2. Backfill open PRs via workflow_dispatch (pr_number is required; there is no sweep mode). PRs opened before the workflow existed otherwise sit at "Expected" forever once the check is required.
3. Verify live: a fork PR posts a status; a non-maintainer approval stays red; a maintainer approval turns it green with no new push; a push returns it red; a PR adding a handle to MAINTAINERS.md cannot self-approve.
4. Add context OpenShell / Core Approval to ruleset 13332227.
5. Merge chore(codeowners): disable wildcard ownership rule #3168.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable) — not applicable, no platform code changed